---
id: namespaces
title: Namespace management - Temporal Cloud feature guide
sidebar_label: Namespaces
description: A Namespace is an isolation unit within the Temporal Platform, providing security boundaries, Workflow management, unique identifiers, and gRPC endpoints in Temporal Cloud.
slug: /cloud/namespaces
toc_max_heading_level: 4
keywords:
  - explanation
  - how-to
  - introduction
  - namespaces
  - temporal cloud
  - term
tags:
  - Namespaces
  - Temporal Cloud
---

A Namespace is a unit of isolation within the Temporal Platform.

- [Create a Namespace](#create-a-namespace)
- [Access a Namespace](#access-namespaces)
- [Manage Namespaces](#manage-namespaces)
- [Delete a Namespace](#delete-a-namespace)

## What is a Cloud Namespace Name? {#temporal-cloud-namespace-name}

A Cloud Namespace Name is a customer-supplied name for a [Namespace](/namespaces) in Temporal Cloud.
Each Namespace Name, such as `accounting-production`, is unique within the scope of a customer's account.
It cannot be changed after the Namespace is provisioned.

Each Namespace Name must conform to the following rules:

- A Namespace Name must contain at least 2 characters and no more than 39 characters.
- A Namespace Name must begin with a letter, end with a letter or number, and contain only letters, numbers, and the hyphen (-) character.
- Each hyphen (-) character must be immediately preceded _and_ followed by a letter or number; consecutive hyphens are not permitted.
- All letters in a Namespace Name must be lowercase.

## What is a Temporal Cloud Account Id? {#temporal-cloud-account-id}

A Temporal Cloud Account Id is a unique customer identifier assigned by Temporal Technologies.
Each Id is a short string of numbers and letters like `f45a2`, at least five characters long.
This account identifier is retained throughout the time each customer uses Temporal Cloud.

At times you may need to know a customer Account Id.
Accessing the account's Namespaces provides an easy way to capture this information.
Each Temporal Namespace use an Account Id suffix.
This is the alphanumeric character string found after the period in any Temporal Cloud Namespace name.

You can retrieve an Account Id from the [Temporal Cloud](https://cloud.temporal.io) Web UI or by using the `tcld` utility at a command line interface (CLI).
Follow these steps.

**From the Temporal Cloud Web UI:**

1. Log into Temporal Cloud.
2. Navigate to the Namespace list page from the left-side vertical navigation.
3. View the Namespaces listed for the user. Each Namespace includes several details:
   - _Status_:
     the Namespace's current state within the Temporal Cloud system, such as Active, Updating, or Deprecated.
   - _Name_:
     a customer-supplied identifier.
     It is unique within the scope of a customer's account.
   - _Region_:
     corresponds to the Namespace's [hosting region](/cloud/service-availability#regions).
   - _Retention_:
     a period during which completed workflows can be recovered and analyzed.
   - _APS Limit_:
     the maximum number of actions per second that a namespace supports.

Each Namespace automatically appends an Account Id suffix to its customer-supplied identifier.
This five-character-or-longer string appears after the name, separated by a period.

| Status | Name                     | Region    | Retention | APS Limit | Export |
| ------ | ------------------------ | --------- | --------- | --------- | ------ |
| Active | your-namespace.123def    | us-west-2 | 30 Days   | 400       | --     |
| Active | another-namespace.123def | us-west-2 | 30 Days   | 400       | --     |

In this Namespace listing sample, the Account Id is 123def.

**From the Command Line:**

1. Use the `tcld` utility to log into an account.

   ```
   tcld login
   ```

   The `tcld` output presents a URL with an activation code at the end. Take note of this code. The utility blocks until the login/activation process completes.

   ```
   Login via this url: https://login.tmprl.cloud/activate?user_code=KTGC-ZPWQ
   ```

   A Web page automatically opens for authentication in your default browser.

2. Visit the browser. Ensure the user code shown by the CLI utility matches the code shown in the Web browser.
   Then, click Confirm in the browser to continue.

   After confirmation, Web feedback lets you know that the CLI "device" is now connected.

3. Return to the command line.
   Issue the following command.

   ```
   tcld namespace list
   ```

   The CLI tool returns a short JSON packet with your namespace information.
   This is the same list found in the Temporal Cloud Web UI Namespaces list.
   Like the browser version, each Namespace uses an Account Id suffix.

   ```
   {
     "namespaces": [
       "your-namespace.123def",
       "another-namespace.123def"
     ],
     "nextPageToken": ""
   }
   ```

In this example, the Account Id is `123def`.

## What is a Cloud Namespace Id? {#temporal-cloud-namespace-id}

A Cloud Namespace Id is a globally unique identifier for a [Namespace](/namespaces) in Temporal Cloud.
A Namespace Id is formed by concatenating the following:

1. A [Namespace Name](#temporal-cloud-namespace-name)
1. A period (.)
1. The [Account Id](#temporal-cloud-account-id) to which the Namespace belongs

For example, for the Account Id `f45a2` and Namespace Name `accounting-production`, the Namespace Id is `accounting-production.f45a2`.

## What is a Cloud gRPC Endpoint? {#temporal-cloud-grpc-endpoint}

Temporal Clients communicate between application code and a Temporal Server by sending and receiving messages via the gRPC protocol.
gRPC is a Remote Procedure Call framework featuring low latency and high performance.
gRPC provides Temporal with an efficient, language-agnostic communication framework.

Every Temporal Namespace uses a gRPC endpoint for communication.
When migrating to Temporal Cloud, you'll need to switch the gRPC endpoint in your code from your current hosting, whether self-hosted or locally-hosted, to Temporal Cloud.

A Namespace-specific gRPC endpoint is found on the detail page for each Cloud Namespace.
Follow these steps to find it:

1. Log into your account on [cloud.temporal.io](https://cloud.temporal.io/namespaces).
2. Navigate to the Namespace list page from the left-side vertical navigation.
3. Tap or click on the Namespace Name to select and open the page for the Namespace whose endpoint you want to retrieve.
4. On the Namespace detail page, locate the Namespace name.
   Just below that is a row of information including the completed Workflow retention policy, the Namespace region, the Actions-Per-Second limit, and the gRPC endpoint.
5. Click the copy icon next to the gRPC address to copy it to your clipboard.

<div className="tdiw">
  <div className="tditw">
    <p className="tdit">gRPC endpoint</p>
  </div>
  <div className="tdiiw" height="207">
    <img className="img_ev3q" src="/img/grpc-endpoint.png" alt="gRPC endpoint" />
  </div>
</div>

## How to create a Namespace in Temporal Cloud {#create-a-namespace}

:::info

The user who creates a [Namespace](/namespaces) is automatically granted [Namespace Admin](/cloud/users#namespace-level-permissions) permission for that Namespace.

To create a Namespace, a user must have the Developer, Account Owner, or Global Admin account-level [Role](/cloud/users#account-level-roles).

:::

:::tip

By default, each account is provisioned with ten Namespaces.
As you start using Namespaces by scheduling Workflows, Temporal Cloud automatically raises your allowance.
This automatic adjustment happens whenever all your Namespaces are in use, up to a maximum of 100 Namespaces.
You can request further increases beyond the 100 Namespace limit by opening a [support ticket](/cloud/support#support-ticket).

:::

{/* What information do I need to create a Namespace in Temporal Cloud? */}

### Information needed to create a Namespace

To create a Namespace in Temporal Cloud, gather the following information:

- [Namespace Name](#temporal-cloud-namespace-name), region, and Cloud Provider
- [Retention Period](/clusters#retention-period) for the [Event History](/workflows#event-history) of closed [Workflow Executions](/workflows#workflow-execution).
- [CA certificate](/cloud/certificates#certificate-requirements) for the Namespace.
- [Codec Server endpoint](/production-deployment/data-encryption#set-your-codec-server-endpoints-with-web-ui-and-cli) to show decoded payloads to users in the Event History for Workflow Executions in the Namespace. For details, see [Securing your data](/production-deployment/data-encryption).
- [Permissions](/cloud/users#namespace-level-permissions) for each user.

{/* How to create a Namespace in Temporal Cloud using Temporal Cloud UI */}

### Create a Namespace using Temporal Cloud UI

1. Gather the information listed earlier in [Information needed to create a Namespace](#information-needed-to-create-a-namespace).
1. Go to the Temporal Cloud UI and log in.
1. On the left side of the window, click **Namespaces**.
1. On the **Namespaces** page, click **Create Namespace** in the upper-right portion of the window.
1. On the **Create Namespace** page in **Name**, enter the Namespace Name.
1. In **Cloud Provider**, select the cloud provider in which to host this Namespace.
1. In **Region**, select the region in which to host this Namespace.
1. In **Retention Period**, specify a value from 1 to 90 days.
   When choosing this value, consider your needs for Event History versus the cost of maintaining that Event History.
   Typically, a development Namespace has a short retention period and a production Namespace has a longer retention period.
   (If you need to change this value later, contact [Temporal Support](/cloud/support#support-ticket).)
1. In **Certificate**, paste the CA certificate for this Namespace.
1. Optional: In **Codec Server**, enter the HTTPS URL (including the port number) of your Codec Server endpoint.
   You may also enable "Pass the user access token with your endpoint" and "Include cross-origin credentials."
   For details, see [Hosting your Codec Server](/production-deployment/data-encryption#set-your-codec-server-endpoints-with-web-ui-and-cli).
1. Click **Create Namespace**.

{/* How to create a Namespace in Temporal Cloud using tcld */}

### Create a Namespace using tcld

See the [`tcld` namespace create](/cloud/tcld/namespace/#create) command reference for details.

## What are some Namespace best practices? {#best-practices}

This section provides general guidance for organizing [Namespaces](/namespaces) across use cases, services, applications, or domains.
Temporal Cloud provides Namespace–as-a-service, so the Namespace is the endpoint.
Customers should consider not only a Namespace naming convention but also how to group or isolate workloads using the Namespace as a boundary.

### Constraints and limitations

Before considering an appropriate Namespace configuration, you should be aware of the following constraints:

- By default, each account is provisioned with ten Namespaces.
  As you create and use your Namespaces, for example by scheduling Workflows, Temporal Cloud automatically raises your limit.
  Our service identifies your usage patterns.
  It responds by slowly increasing your allowance, up to 100 Namespaces.
  You can request further increases beyond the 100 Namespace limit by opening a [support ticket](/cloud/support#support-ticket).
- Cross-Namespace communications between [Workflows](/workflows) is not yet supported.
  For now, you can use the [SDK client](/encyclopedia/temporal-sdks#temporal-client) from within an [Activity](/activities) as a workaround.
- Each Namespace has a rate limit, which is measured in Actions per second (APS).
  A namespace may be throttled when its throughput becomes too high.
  Throttling means limiting the rate at which actions are performed to prevent overloading the system.
  A Namespace's default limit is set at 400 APS and automatically adjusts based on recent usage (over the prior 7 days).
  Your APS limit will never fall below this default value.
- Each Namespace has a service-level agreement (SLA) of 99.9% uptime.
- For now, Namespaces are single-region only.
- A Namespace is a security isolation boundary.
  Access to Temporal by [Worker Processes](/workers#worker-process) is permitted at the Namespace level.
  Isolating applications or environments (development, test, staging, production) should take this into consideration.
- A Namespace is an endpoint.
  To access a Namespace from a Temporal Client requires mTLS authorization, which requires [CA certificates](/cloud/certificates#ca-certificates).
- [Workflow Id](/workflows#workflow-id) uniqueness is per Namespace.
- [Task Queue](/workers#task-queue) names are unique per Namespace.
- Closed Workflow retention is per Namespace.
- RBAC [permissions](/cloud/users#namespace-level-permissions) are implemented at the Namespace level.

### General guidance

Namespace configuration requires some consideration.
Following are some general guidelines to consider.

- Namespaces are usually defined per use case.
  A use case can encompass a broad range of Workflow types and a nearly unlimited scale of concurrent [Workflow Executions](/workflows#workflow-execution).
- Namespaces can be split along additional boundaries such as service, application, domain or even sub-domain.
- Environments such as production and development usually have requirements for isolation.
  We recommend that each environment has its own Namespace.
- Namespaces should be used to reduce the "blast radius" for mission-critical applications.
- Workflows that need to communicate with each other should (for now) be in the same Namespace.
- If you need to share Namespaces across team or domain boundaries, be sure to ensure the uniqueness of Workflow Ids.

### Examples

Following are some ideas about how to organize Namespaces.

#### Example 1: Namespace per use case and environment

We recommend using one Namespace for each use case and environment combination for simple configurations in which multiple services and team or domain boundaries don't exist.

Sample naming convention:

<pre>&lt;use-case>_&lt;environment></pre>

#### Example 2: Namespace per use case, service, and environment

We recommend using one Namespace for each use case, service, and environment combination when multiple services that are part of same use case communicate externally to Temporal via API (HTTP/gRPC).

Sample naming convention:

<pre>&lt;use-case>_&lt;service>_&lt;environment></pre>

#### Example 3: Namespace per use case, domain, and environment

We recommend using one namespace per use case, domain, and environment combination when multiple services that are part of the same use case need to communicate with each another via [Signals](/encyclopedia/workflow-message-passing#sending-signals) or by starting [Child Workflows](/encyclopedia/child-workflows).
In this case, though, you must be mindful about Workflow Id uniqueness by prefixing each Workflow Id with a service-specific string.
The name of each Task Queue must also be unique.
If multiple teams are involved, the domain could also represent a team boundary.

Sample naming convention:

<pre>&lt;use-case>_&lt;domain>_&lt;environment></pre>

Sample workflowId convention:

<pre>&lt;service-string>_&lt;workflow-id></pre>

## How to access a Namespace in Temporal Cloud {#access-namespaces}

{/* How to access a Namespace in Temporal Cloud */}

Each Namespace in Temporal Cloud has two unique endpoints, both of which include the [Namespace Id](#temporal-cloud-namespace-id).

- For programmatic access, a gRPC endpoint in the form `<NamespaceId>.tmprl.cloud`; for example, `accounting-production.f45a2.tmprl.cloud:7233`.
- For accessing Temporal Web UI, an HTTPS endpoint in the form `https://cloud.temporal.io/namespaces/<namespaceId>`; for example, `https://cloud.temporal.io/namespaces/accounting-production.f45a2`.

To ensure the security of your data, all traffic to and from your Namespace is encrypted.
However, for enhanced protection, you have additional options:

- (recommended) Set up private connectivity by [creating a ticket for Temporal Support](/cloud/support#support-ticket).
- Set up your allow list for outgoing network requests from your Clients and Workers with the IP address ranges of the Cloud Provider region in which your Namespace is located:
  - [AWS IP address ranges](https://docs.aws.amazon.com/vpc/latest/userguide/aws-ip-ranges.html)
  - [GCP IP address ranges](https://cloud.google.com/compute/docs/faq#find_ip_range)

## How to manage Namespaces in Temporal Cloud {#manage-namespaces}

{/* How to manage Namespaces in Temporal Cloud using Temporal Cloud UI */}

### Manage Namespaces in Temporal Cloud using Temporal Cloud UI

To list Namespaces:

- On the left side of the window, select **Namespaces**.

To edit a Namespace (including custom Search Attributes, certificates, certificate filters, Codec Server endpoint, permissions, and users), find the Namespace and do either of the following:

- On the right end of the Namespace row, select the three vertical dots (⋮). Click **Edit**.
- Select the Namespace name. In the top-right portion of the page, select **Edit**.

On the **Edit** page, you can do the following:

- Add a [custom Search Attribute](/visibility#custom-search-attributes).
- [Manage CA certificates](/cloud/certificates).
- [Manage certificate filters](/cloud/certificates#manage-certificate-filters-using-temporal-cloud-ui).
- Set [Codec Server endpoint](/production-deployment/data-encryption#set-your-codec-server-endpoints-with-web-ui-and-cli) for all users on the Namespace.
  Each user on the Namespace has the option to [override this setting](/production-deployment/data-encryption#web-ui) in their browser.
- Manage [Namespace-level permissions](/cloud/users#namespace-level-permissions).
- Add users.

To add a user to a Namespace, scroll to the bottom of the page and select **Add User**.

After you make changes, select **Save** in the top-right or bottom-left portion of the page.

{/* How to manage Namespaces in Temporal Cloud using tcld */}

### Manage Namespaces in Temporal Cloud using tcld

To list Namespaces and get information about them, use the following [tcld](/cloud/tcld/) commands:

- [tcld namespace list](/cloud/tcld/namespace/#list)
- [tcld namespace get](/cloud/tcld/namespace/#get)

To manage certificates, use the [tcld namespace accepted-client-ca](/cloud/tcld/namespace/#accepted-client-ca) commands.
For more information, see [How to manage certificates in Temporal Cloud](/cloud/certificates).

To manage certificate filters, use the [tcld namespace certificate-filters](/cloud/tcld/namespace/#certificate-filters) commands.
For more information, see [How to manage certificate filters in Temporal Cloud](/cloud/certificates#manage-certificate-filters).

## How to delete a Namespace in Temporal Cloud {#delete-a-namespace}

:::info

To delete a Namespace, a user must have Namespace Admin [permission](/cloud/users#namespace-level-permissions) for that Namespace.

:::

### Delete a Namespace using Temporal Cloud UI

1. Go to the Temporal Cloud UI and log in.
1. On the left side of the window, select **Namespaces**.
1. On the **Namespaces** page, select a Namespace Name.
1. On the Namespace page, select **Edit** in the upper-right portion of the window.
1. On the **Edit** Namespace page, select **Delete Namespace** in the upper-right portion of the window.
1. In the **Delete Namespace** dialog, type `DELETE` to confirm the deletion of that Namespace.
1. Select **Delete**.

After deleting a Temporal Cloud Namespace, the Temporal Service immediately removes the Namespace's Workflow Executions and Task Queues.
Make sure all Workflows have been completed, canceled, or terminated before removing a Namespace.
The Namespace removal is permanent.

Closed Workflow Histories remain in Temporal storage until the user-defined retention period expires.
This period reflects the policy in effect when the Workflow Execution was closed.

For further questions or concerns, contact [Support](https://docs.temporal.io/cloud/support#support-ticket).

### Delete a Namespace using tcld

See the [tcld namespace delete](/cloud/tcld/namespace/#delete) command reference for details.
